home *** CD-ROM | disk | FTP | other *** search
/ Chip 2007 January, February, March & April / Chip-Cover-CD-2007-02.iso / Pakiet bezpieczenstwa / mini Pentoo LiveCD 2006.1 / mpentoo-2006.1.iso / livecd.squashfs / usr / include / gaim / buddyicon.h < prev    next >
C/C++ Source or Header  |  2005-10-18  |  7KB  |  260 lines
  1. /**
  2.  * @file buddyicon.h Buddy Icon API
  3.  * @ingroup core
  4.  *
  5.  * gaim
  6.  *
  7.  * Gaim is the legal property of its developers, whose names are too numerous
  8.  * to list here.  Please refer to the COPYRIGHT file distributed with this
  9.  * source distribution.
  10.  *
  11.  * This program is free software; you can redistribute it and/or modify
  12.  * it under the terms of the GNU General Public License as published by
  13.  * the Free Software Foundation; either version 2 of the License, or
  14.  * (at your option) any later version.
  15.  *
  16.  * This program is distributed in the hope that it will be useful,
  17.  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  18.  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  19.  * GNU General Public License for more details.
  20.  *
  21.  * You should have received a copy of the GNU General Public License
  22.  * along with this program; if not, write to the Free Software
  23.  * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
  24.  */
  25. #ifndef _GAIM_BUDDYICON_H_
  26. #define _GAIM_BUDDYICON_H_
  27.  
  28. typedef struct _GaimBuddyIcon GaimBuddyIcon;
  29.  
  30. #include "account.h"
  31. #include "blist.h"
  32.  
  33. struct _GaimBuddyIcon
  34. {
  35.     GaimAccount *account;  /**< The account the user is on.        */
  36.     char *username;        /**< The username the icon belongs to.  */
  37.  
  38.     void  *data;           /**< The buddy icon data.               */
  39.     size_t len;            /**< The length of the buddy icon data. */
  40.  
  41.     int ref_count;         /**< The buddy icon reference count.    */
  42. };
  43.  
  44. /**************************************************************************/
  45. /** @name Buddy Icon API                                                  */
  46. /**************************************************************************/
  47. /*@{*/
  48.  
  49. /**
  50.  * Creates a new buddy icon structure.
  51.  *
  52.  * @param account   The account the user is on.
  53.  * @param username  The username the icon belongs to.
  54.  * @param icon_data The buddy icon data.
  55.  * @param icon_len  The buddy icon length.
  56.  *
  57.  * @return The buddy icon structure.
  58.  */
  59. GaimBuddyIcon *gaim_buddy_icon_new(GaimAccount *account, const char *username,
  60.                                    void *icon_data, size_t icon_len);
  61.  
  62. /**
  63.  * Destroys a buddy icon structure.
  64.  *
  65.  * If the buddy icon's reference count is greater than 1, this will
  66.  * just decrease the reference count and return.
  67.  *
  68.  * @param icon The buddy icon structure to destroy.
  69.  */
  70. void gaim_buddy_icon_destroy(GaimBuddyIcon *icon);
  71.  
  72. /**
  73.  * Increments the reference count on a buddy icon.
  74.  *
  75.  * @param icon The buddy icon.
  76.  *
  77.  * @return @a icon.
  78.  */
  79. GaimBuddyIcon *gaim_buddy_icon_ref(GaimBuddyIcon *icon);
  80.  
  81. /**
  82.  * Decrements the reference count on a buddy icon.
  83.  *
  84.  * If the reference count reaches 0, the icon will be destroyed.
  85.  *
  86.  * @param icon The buddy icon.
  87.  *
  88.  * @return @a icon, or @c NULL if the reference count reached 0.
  89.  */
  90. GaimBuddyIcon *gaim_buddy_icon_unref(GaimBuddyIcon *icon);
  91.  
  92. /**
  93.  * Updates every instance of this icon.
  94.  *
  95.  * @param icon The buddy icon.
  96.  */
  97. void gaim_buddy_icon_update(GaimBuddyIcon *icon);
  98.  
  99. /**
  100.  * Caches a buddy icon associated with a specific buddy to disk.
  101.  *
  102.  * @param icon  The buddy icon.
  103.  * @param buddy The buddy that this icon belongs to.
  104.  */
  105. void gaim_buddy_icon_cache(GaimBuddyIcon *icon, GaimBuddy *buddy);
  106.  
  107. /**
  108.  * Removes cached buddy icon for a specific buddy.
  109.  *
  110.  * @param buddy The buddy for which to remove the cached icon.
  111.  */
  112. void gaim_buddy_icon_uncache(GaimBuddy *buddy);
  113.  
  114. /**
  115.  * Sets the buddy icon's account.
  116.  *
  117.  * @param icon    The buddy icon.
  118.  * @param account The account.
  119.  */
  120. void gaim_buddy_icon_set_account(GaimBuddyIcon *icon, GaimAccount *account);
  121.  
  122. /**
  123.  * Sets the buddy icon's username.
  124.  *
  125.  * @param icon     The buddy icon.
  126.  * @param username The username.
  127.  */
  128. void gaim_buddy_icon_set_username(GaimBuddyIcon *icon, const char *username);
  129.  
  130. /**
  131.  * Sets the buddy icon's icon data.
  132.  *
  133.  * @param icon The buddy icon.
  134.  * @param data The buddy icon data.
  135.  * @param len  The length of the icon data.
  136.  */
  137. void gaim_buddy_icon_set_data(GaimBuddyIcon *icon, void *data, size_t len);
  138.  
  139. /**
  140.  * Returns the buddy icon's account.
  141.  *
  142.  * @param icon The buddy icon.
  143.  *
  144.  * @return The account.
  145.  */
  146. GaimAccount *gaim_buddy_icon_get_account(const GaimBuddyIcon *icon);
  147.  
  148. /**
  149.  * Returns the buddy icon's username.
  150.  *
  151.  * @param icon The buddy icon.
  152.  *
  153.  * @return The username.
  154.  */
  155. const char *gaim_buddy_icon_get_username(const GaimBuddyIcon *icon);
  156.  
  157. /**
  158.  * Returns the buddy icon's data.
  159.  *
  160.  * @param icon The buddy icon.
  161.  * @param len  The returned icon length.
  162.  *
  163.  * @return The icon data.
  164.  */
  165. const void *gaim_buddy_icon_get_data(const GaimBuddyIcon *icon, size_t *len);
  166.  
  167. /**
  168.  * Returns an extension corresponding to the buddy icon's file type.
  169.  *
  170.  * @param icon The buddy icon.
  171.  *
  172.  * @return The icon's extension.
  173.  */
  174. const char *gaim_buddy_icon_get_type(const GaimBuddyIcon *icon);
  175.  
  176. /*@}*/
  177.  
  178. /**************************************************************************/
  179. /** @name Buddy Icon Subsystem API                                        */
  180. /**************************************************************************/
  181. /*@{*/
  182.  
  183. /**
  184.  * Sets a buddy icon for a user.
  185.  *
  186.  * @param account   The account the user is on.
  187.  * @param username  The username of the user.
  188.  * @param icon_data The icon data.
  189.  * @param icon_len  The length of the icon data.
  190.  */
  191. void gaim_buddy_icons_set_for_user(GaimAccount *account, const char *username,
  192.                                    void *icon_data, size_t icon_len);
  193.  
  194. /**
  195.  * Returns the buddy icon information for a user.
  196.  *
  197.  * @param account  The account the user is on.
  198.  * @param username The username of the user.
  199.  *
  200.  * @return The icon data if found, or @c NULL if not found.
  201.  */
  202. GaimBuddyIcon *gaim_buddy_icons_find(GaimAccount *account,
  203.                                      const char *username);
  204.  
  205. /**
  206.  * Sets whether or not buddy icon caching is enabled.
  207.  *
  208.  * @param caching TRUE of buddy icon caching should be enabled, or
  209.  *                FALSE otherwise.
  210.  */
  211. void gaim_buddy_icons_set_caching(gboolean caching);
  212.  
  213. /**
  214.  * Returns whether or not buddy icon caching should be enabled.
  215.  *
  216.  * The default is TRUE, unless otherwise specified by
  217.  * gaim_buddy_icons_set_caching().
  218.  *
  219.  * @return TRUE if buddy icon caching is enabled, or FALSE otherwise.
  220.  */
  221. gboolean gaim_buddy_icons_is_caching(void);
  222.  
  223. /**
  224.  * Sets the directory used to store buddy icon cache files.
  225.  *
  226.  * @param cache_dir The directory to store buddy icon cache files to.
  227.  */
  228. void gaim_buddy_icons_set_cache_dir(const char *cache_dir);
  229.  
  230. /**
  231.  * Returns the directory used to store buddy icon cache files.
  232.  *
  233.  * The default directory is GAIMDIR/icons, unless otherwise specified
  234.  * by gaim_buddy_icons_set_cache_dir().
  235.  *
  236.  * @return The directory to store buddy icon cache files to.
  237.  */
  238. const char *gaim_buddy_icons_get_cache_dir(void);
  239.  
  240. /**
  241.  * Returns the buddy icon subsystem handle.
  242.  *
  243.  * @return The subsystem handle.
  244.  */
  245. void *gaim_buddy_icons_get_handle();
  246.  
  247. /**
  248.  * Initializes the buddy icon subsystem.
  249.  */
  250. void gaim_buddy_icons_init();
  251.  
  252. /**
  253.  * Uninitializes the buddy icon subsystem.
  254.  */
  255. void gaim_buddy_icons_uninit();
  256.  
  257. /*@}*/
  258.  
  259. #endif /* _GAIM_BUDDYICON_H_ */
  260.